
/*
 * Copyright (C) 2006 Sun Microsystems, Inc. All rights reserved. Use is
 * subject to license terms.
 */ 

package com.cainli.task;

import java.util.List;


/**
 * Listener used for observing {@code Task} execution.  
 * A {@code TaskListener} is particularly 
 * useful for monitoring the the intermediate results 
 * {@link AbstractTask#publish published} by a Task in situations
 * where it's not practical to override the Task's 
 * {@link AbstractTask#process process} method.  Note that if 
 * what you really want to do is monitor a Task's state 
 * and progress, a PropertyChangeListener is probably more
 * appropriate.
 * <p>
 * The Task class runs all TaskListener methods on the event dispatching
 * thread and the source of all TaskEvents is the Task object.
 * 
 * @see AbstractTask#addTaskListener
 * @see AbstractTask#removeTaskListener
 * @see AbstractTask#addPropertyChangeListener
 * 
 * @author Hans Muller (Hans.Muller@Sun.COM)
 */
public interface TaskListener<T, V> {

    /**
     * Called just before the Task's {@link AbstractTask#doInBackground
     * doInBackground} method is called, i.e. just before the task
     * begins running.  The {@code event's} source is the Task and its
     * value is null.
     * 
     * @param event a TaskEvent whose source is the {@code Task} object, value is null
     * @see AbstractTask#doInBackground
     * @see TaskEvent#getSource
     */
    void doInBackground(TaskEvent<Void> event);

    /**
     * Called each time the Task's {@link AbstractTask#process process} method is called.
     * The value of the event is the list of values passed to the process method.  
     * 
     * @param event a TaskEvent whose source is the {@code Task} object and whose
     *     value is a list of the values passed to the {@code Task.process()} method
     * @see AbstractTask#doInBackground
     * @see AbstractTask#process
     * @see TaskEvent#getSource
     * @see TaskEvent#getValue
     */
    void process(TaskEvent<List<V>> event);

    /**
     * Called after the Task's {@link AbstractTask#succeeded succeeded}
     * completion method is called.  The event's value is the value
     * returned by the Task's {@code get} method, i.e. the value that
     * is computed by {@link AbstractTask#doInBackground}.
     *
     * @param event a TaskEvent whose source is the {@code Task} object, and 
     *     whose value is the value returned by {@code Task.get()}.
     * @see AbstractTask#succeeded
     * @see TaskEvent#getSource
     * @see TaskEvent#getValue
     */
    void succeeded(TaskEvent<T> event);

    /**
     * Called after the Task's {@link AbstractTask#failed failed} completion
     * method is called.  The event's value is the Throwable passed to
     * {@code Task.failed()}.
     *
     * @param event a TaskEvent whose source is the {@code Task} object, and 
     *     whose value is the Throwable passed to {@code Task.failed()}.
     * @see AbstractTask#failed
     * @see TaskEvent#getSource
     * @see TaskEvent#getValue
     */
    void failed(TaskEvent<Throwable> event);

    /**
     * Called after the Task's {@link AbstractTask#cancelled cancelled} method
     * is called.  The {@code event's} source is the Task and its
     * value is null.
     *
     * @param event a TaskEvent whose source is the {@code Task} object, value is null
     * @see AbstractTask#cancelled
     * @see AbstractTask#get
     * @see TaskEvent#getSource
     */
    void cancelled(TaskEvent<Void> event);

    /**
     * Called after the Task's {@link AbstractTask#interrupted interrupted} method is called.
     * The {@code event's} source is the Task and its value is
     * the InterruptedException passed to {@code Task.interrupted()}.
     *
     * @param event a TaskEvent whose source is the {@code Task} object, and 
     *     whose value is the InterruptedException passed to {@code Task.interrupted()}.
     * @see AbstractTask#interrupted
     * @see TaskEvent#getSource
     * @see TaskEvent#getValue
     */
    void interrupted(TaskEvent<InterruptedException> event);

    /**
     * Called after the Task's {@link AbstractTask#finished finished} method is called.
     * The {@code event's} source is the Task and its value is null.
     *
     * @param event a TaskEvent whose source is the {@code Task} object, value is null.
     * @see AbstractTask#interrupted
     * @see TaskEvent#getSource
     */
    void finished(TaskEvent<Void> event);

    /** 
     * Convenience class that stubs all of the TaskListener interface
     * methods.  Using TaskListener.Adapter can simplify building 
     * TaskListeners:
     * <pre>
     * </pre>
     */
    class Adapter<T, V> implements TaskListener<T, V> {
    public void doInBackground(TaskEvent<Void> event) { return;}
    public void process(TaskEvent<List<V>> event) {}
    public void succeeded(TaskEvent<T> event) {}
    public void failed(TaskEvent<Throwable> event) {}
    public void cancelled(TaskEvent<Void> event) {}
    public void interrupted(TaskEvent<InterruptedException> event) {}
    public void finished(TaskEvent<Void> event) {}
    }
}